<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
<html><head><title>Programming in Lua : 13.3</title>
<link rel="stylesheet" type="text/css" href="pil.css">
</head>
<body>
<p class="warning">
<A HREF="contents.html"><IMG TITLE="Programming in Lua (first edition)" SRC="capa.jpg" ALT="" ALIGN="left"></A>This first edition was written for Lua 5.0. While still largely relevant for later versions, there are some differences.<BR>The third edition targets Lua 5.2 and is available at <A HREF="http://www.amazon.com/exec/obidos/ASIN/859037985X/theprogrammil3-20">Amazon</A> and other bookstores.<BR>By buying the book, you also help to <A HREF="../donations.html">support the Lua project</A>.
</p>
<table width="100%" class="nav">
<tr>
<td width="10%" align="left"><a href="13.2.html"><img border="0" src="left.png" alt="Previous"></a></td>
<td width="80%" align="center"><a href="contents.html"><font face="Helvetica,Arial,sanserif">
<font color="gray">Programming in </font><font color="blue"> Lua</font>
</font></a></td>
<td width="10%" align="right"><a href="13.4.html"><img border="0" src="right.png" alt="Next"></a></td>
</tr>
<tr>
<td width="10%" align="left"></td>
<td width="80%" align="center"><a href="contents.html#P2">Part II. Tables and Objects</a>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
<a href="contents.html#13">Chapter 13. Metatables and Metamethods</a></td>
<td width="10%" align="right"></td></tr>
</table>
<hr/>
<p><h2>13.3 &ndash; Library-Defined Metamethods</h2>

<p>It is a common practice for some libraries to
define their own fields in metatables.
So far, all the metamethods we have seen are for the Lua core.
It is the virtual machine that detects that the values involved
in an operation have metatables
and that these metatables define metamethods for that operation.
However, because the metatable is a regular table,
anyone can use it.

<p>The <code>tostring</code> function provides a typical example.
As we saw earlier, <code>tostring</code> represents tables in a
rather simple format:
<pre>
    print({})      --> table: 0x8062ac0
</pre>
(Note that <code>print</code> always calls <code>tostring</code> to format its output.)
However, when formatting an object,
<code>tostring</code> first checks whether the object has a metatable with
a <code>__tostring</code> field.
If this is the case, <code>tostring</code> calls the corresponding value
(which must be a function) to do its job,
passing the object as an argument.
Whatever this metamethod returns is the result of <code>tostring</code>.

<p>In our example with sets,
we have already defined a function to present a set as a string.
So, we need only to set the <code>__tostring</code> field in the set metatable:
<pre>
    Set.mt.__tostring = Set.tostring
</pre>
After that, whenever we call <code>print</code> with a set as its argument,
<code>print</code> calls <code>tostring</code> that calls <code>Set.tostring</code>:
<pre>
    s1 = Set.new{10, 4, 5}
    print(s1)    --> {4, 5, 10}
</pre>

<p>The <code>setmetatable</code>/<code>getmetatable</code>
functions use a metafield also,
in this case to protect metatables.
Suppose you want to protect your sets,
so that users can neither see nor change their metatables.
If you set a <code>__metatable</code> field in the metatable,
<code>getmetatable</code> will return the value of this field,
whereas <code>setmetatable</code> will raise an error:
<pre>
    Set.mt.__metatable = "not your business"
    
    s1 = Set.new{}
    print(getmetatable(s1))     --> not your business
    setmetatable(s1, {})
      stdin:1: cannot change protected metatable
</pre>

<hr/>
<table width="100%" class="nav">
<tr valign="top">
<td width="90%" align="left">
<small>
  Copyright &copy; 2003&ndash;2004 Roberto Ierusalimschy.  All rights reserved.
</small>
</td>
<td width="10%" align="right"><a href="13.4.html"><img border="0" src="right.png" alt="Next"></a></td>
</tr>
</table>


</body></html>

